feat: launch coding agents with Pulsing companions - #80

Overview

Add pulsing -- codex for mailbox-based collaboration between coding-agent sessions. Each invocation gets one supervised Pulsing companion, and each native agent/subagent gets a separate bounded in-memory mailbox bound to harness-provided MCP thread metadata. No separate mailbox service is required.

Both machines use the same configuration:

SEED=10.0.0.10:8100 pulsing -- codex

The machine owning the seed IP listens there automatically. Other machines select their source interface from the route to the seed and bind an available port. The seed is a network entry point, not a central mailbox store.

Implementation

• Supervise the companion and external command with readiness checks, per-invocation Codex MCP injection, inherited terminal I/O, signal forwarding, exit-code propagation and paired shutdown. Global Codex configuration is unchanged. Generic commands receive a documented environment contract.
• Automatically select seed ownership and joiner addresses, including bounded re-planning on local seed-port races. Explicit address overrides and standalone SEED=1 remain supported.
• Derive agent identities from authoritative MCP _meta.threadId; reject missing metadata instead of sharing a parent identity. Route remote deliveries through Pulsing actor discovery.
• Remove SQLite, database schema/WAL and restore logic. Mailboxes and directory roles exist only in RAM. Default per-mailbox limits are 10,000 messages and an 8 MiB logical payload budget, not an RSS guarantee. Restart loses messages, roles, leases and idempotency keys; stable identity does not imply recovered state.
• Record actor-owned JSONL observations: lifecycle, identity bindings, full deliveries, read/claim/finish deltas, retries, receipts and rejections. Actor incarnation IDs and sequences distinguish restarts. Logs are never loaded into live actors. Existing historical databases are not deleted.
• Add python -m pulsing.mailbox replay LOG... --format json|markdown --output NEWFILE for offline inspection. Detect sequence gaps, conflicting duplicate events and malformed/truncated records. Replay does not spawn actors, rerun tools or resume models.
• Use --runtime-dir for process rendezvous and logs; retain --state-dir as an alias only. Logging is synchronous and observational, not an atomic distributed journal or crash-recovery protocol. Log I/O failures surface to callers; retention remains operator-managed.
• Keep a separately installable pulsing Codex plugin generator for standalone use.
• Keep optional --audit-log / PULSING_AUDIT_LOG MCP request/response auditing with known credential fields fingerprinted and authorization headers omitted.
• Document the design and a completed, operator-authorized 600-second Fermat council run: exactly 20 logical agents across two Codex roots (coordinator and arbiter), 18 children, four specialist groups, evidence auditor and proof-graph checker. Includes cross-group challenges, dynamic dispute panels, evidence-constrained arbitration, one appeal, blind controls and externally enforced cutoff. The goal is to reconstruct and critique a theorem-dependent FLT derivation, not announce a new proof from consensus.

Validation of the current in-memory implementation

• .venv/bin/pytest tests/python --ignore=tests/python/test_chaos.py -q: 688 passed, 16 skipped.
• .venv/bin/ruff check python tests examples: passed.
• Scoped changed-Python formatting: passed.
• .venv/bin/python examples/python/mailbox_collaboration.py: passed with real actors and deterministic roles.
• Maturin wheel build, package-content checks, isolated target installation, volatile lifecycle and offline replay CLI smoke: passed. Installation used uv pip because the development venv has no pip module.
• Restart tests verify old mail/roles are absent, while historical messages remain inspectable offline. Capacity, failed log writes, no-file library use, repeated replay input and invalid log histories are tested.
• After the memory refactor, an explicitly authorized real-model run used two Codex roots and eighteen native subagents, exactly twenty distinct threads. It produced 307 messages (including 20 READY), 124 cross-instance messages, 79 cross-specialist-group messages and 1,465 MCP tool calls, with no recorded tool errors or missing responses. All twenty visible conversations were exported. The public result report is docs/src/design/fermat-council-results.md.
• The real-model run did not meet all protocol acceptance criteria: complete roster registration took 273.090s rather than 45s; some panels finished late; verdicts were sent at 570.795–570.892s; 37 final-report messages remained unread at the 600s cutoff, and C0 did not send a separate FINAL. No post-cutoff mail was delivered. The mathematical outcome is conditional reconstruction, not a new or fully independently verified FLT proof.
• Under this low load, mail_send server-boundary p50/p95 was 3.644/4.966ms, but delivery-to-read p50/p95 was 30.919/134.942s. 214/323 mail_list calls returned empty results. These measurements include polling/scheduling limitations; they are not a throughput benchmark or cross-backend comparison.
• Real actor-log replay through the CLI matched the offline snapshot; all 99 archived files passed SHA-256/ZIP checks; the run directory contained no SQLite files. Raw conversations, native thread metadata, local execution scripts and audit archives remain private and are not in the PR. The public design/configuration is not a general automatic execution harness.
• For the final documentation-only commit: .venv/bin/pytest tests/python/mailbox -q passed (73 passed); git diff --check and relative Markdown link validation passed. The full Python suite above belongs to the implementation validation; it was not rerun for the documentation-only change. The documentation site build was not run.

Historical real-model evidence — previous SQLite implementation only

Before the memory refactor, two Codex roots with ten native subagents each exercised MCP identity injection and free peer messaging. A 600-second discussion produced 206 messages, 170 direct peer messages, 90 cross-instance peer messages and 1,321 MCP calls without recorded transport/tool errors. These historical observations do not validate the current memory backend. Private runtime conversations, databases, credentials and audit archives are not included.

Existing aggregate-check limitation

PATH="$PWD/.venv/bin:$PATH" just check passes Rust formatting, then stops because unchanged examples/python/README.md code blocks need formatting under the installed Ruff version. The same file-level failure was reproduced from origin/main. No unrelated formatting cleanup is included. The aggregate command did not reach Rust Clippy/tests; those were not run separately. Python lint/tests were run independently above.

Scope and limitations

• Real TCP/MCP integration uses independent processes on one machine; physical multi-host routing/firewall validation remains outstanding.
• Trusted private clusters only; harness identity binding is not authentication between hostile actors.
• Mailboxes are created on first tool use, not from native spawn notifications.
• No automatic model wakeup/re-execution, HA, replication, file synchronization or exactly-once business-side-effect guarantee.
• Actor/MCP logs contain discussion content; do not send secrets in mail. Known-field redaction is not a general secret detector.
• Bounded mailboxes reject new content at capacity; no automatic eviction or retention policy is introduced.

Review entry points

• python/pulsing/cli/launch.py and python/pulsing/cli/network.py: process lifecycle and network planning.
• python/pulsing/mailbox/companion.py: per-thread binding and distributed lookup.
• python/pulsing/mailbox/actors.py, events.py, replay.py: RAM state and offline observations.
• tests/python/mailbox/test_launcher.py, test_mcp_stdio.py, test_replay.py: process, restart and log checks.
• docs/src/design/fermat-council-experiment.md, examples/python/fermat_council.json and docs/src/design/fermat-council-results.md: experiment design, role/phase configuration, measured results and protocol deviations.

Relates to #79.